home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / C / LIB / DESK / CORE / Desk / !Help next >
Text File  |  1996-09-11  |  8KB  |  242 lines
  1.     Desk release 3.00beta (06 Sep 1996)
  2.     •••••••••••••••••••••••••••••••••••
  3.  
  4.  
  5.  
  6. Introduction
  7. ————————————
  8.  
  9. This is a beta release of the Desk library. 
  10.  
  11. Desk is a new version of the DeskLib library. The main changes are error
  12. handling, names, the directory structure, and an extra build for module
  13. code. There are also a few new functions and sub-libraries.
  14.  
  15. The reason for the new library is that it wasn't possible to update
  16. DeskLib to use the new error handling while preserving backwards
  17. compatibility.
  18.  
  19. I'm fully aware that releasing an incompatible version of a wildly used
  20. library like DeskLib may be unpopular, but it was already proving
  21. difficult to add certain types of code to DeskLib because of it's
  22. primitive error handling, so making radical changes had to happen at
  23. some stage.
  24.  
  25.  
  26.  
  27. Names
  28. —————
  29.  
  30. Every function, variable, typedef etc etc name has been prefixed with
  31. 'Desk_'. Thus 'Desk_Event_Initialise', 'Desk_Wimp_Poll' etc.
  32.  
  33. This has been done so that Desk can be used with other libraries without
  34. name-clashes. For example, DeskLib's Wimp_ veneers clash badly with the
  35. #defines used by OSLib, RISC _OSLib and Acorn's "swis.h" etc.
  36.  
  37. Also, the new error-handling means that Desk functions behave slightly
  38. differently from the equivalent DeskLib ones (eg they don't return an
  39. error code), so the names have to be different.
  40.  
  41. The new names are 5 characters longer which might seem clumsy, but I
  42. think that the benefits more than compensate for this. It would be a
  43. relatively simple task to write some headers which macro Desk's names to
  44. the old DeskLib names without the prefix.
  45.  
  46. Also, all variables such as 'event_taskhandle' are now called
  47. 'Desk_Event_taskhandle' rather than 'Desk_event_taskhandle'. The
  48. capitalised 'Event' means that the object occupies memory, as opposed to
  49. structure names such as 'Desk_event_pollblock'.
  50.  
  51. Note that all structure field-names are identical to the DeskLib ones.
  52.  
  53.  
  54.  
  55.  
  56.  
  57. Error handling
  58. ——————————————
  59.  
  60. Most functions have been changed to make use of the 'Error2' sublibrary,
  61. which was introduced in DeskLib betas after DeskLib release 2.30.
  62.  
  63. All (not quite all yet) swi veneers now send any error straight to the
  64. Error2 system. This is done either by calling the non-X form and relying
  65. on the C runtime system to convert any error into a signal which can be
  66. caught by Error2, or calling the X form and then branching to
  67. Desk_Error2_CheckOS if the V flag is set.
  68.  
  69. The first method is slightly simpler, but doesn't work in SVC mode (the
  70. C runtime system doesn't convert OS errors to a signal in SVC) so is
  71. only used for Wimp SWIs which will always (I think) be called from USR
  72. mode (for example, the task part of module-tasks still run in USR mode).
  73.  
  74. It would have been possible to put some conditional assembley so that
  75. the non-X form is used for non-module builds of the library, but this is
  76. a lot of hastle, and the branch to the Error2 handling after an X SWI is
  77. only one instruction (it's a macro in 'C:Desk.sh.Macros').
  78.  
  79. This means that code can use C++-style exception handling (see the
  80. Jump.h and JumpAuto.h files), so you can malloc memory, call library
  81. functions etc etc without worrying about error-return codee after every
  82. function call.
  83.  
  84. The client application is required to call Desk_Error2_Init_JumpSig() to
  85. initialise the error system.
  86.  
  87. I think there is a problem in that this will catch SIGSTACK - the error
  88. handler is compiled with standard stack-checking, so an infinite loop
  89. will result...
  90.  
  91. Note that you are forced to use the Error2-system when using Desk - any
  92. error not caught (eg because you didn't call Desk_Error2_Init_JumpSig())
  93. will halt the program.
  94.  
  95.  
  96.  
  97.  
  98. Directory structure
  99. ———————————————————
  100.  
  101. Everything is in a 'Desk' directory, rather than an application
  102. directory, which is intended to be put into C$Path. Hence headers are
  103. included with '#include "Desk.Wimp.h"'. This means that Desk is a more
  104. conventional library, rather than setting its own system variables etc
  105. which is rather unnecessary I think.
  106.  
  107. Source code is /within/ the .o directory, which may seem a little
  108. strange. It is also within a '!DeskSrc' application directory, so the
  109. code can be compiled with complete filenames using the
  110. 'Desk_Sources$Dir' system variable, which can aid debugging.
  111.  
  112. Building the various versions of Desk is done with my freeware 'Makatic'
  113. tools, which cuts down the number of obscure script files that were in
  114. DeskLib.
  115.  
  116.  
  117.  
  118.  
  119. Changes to sublibraries
  120. ———————————————————————
  121.  
  122. The file 'Desk.History' contains a list of all changes since DeskLib
  123. 2.30. Due to extreme lack of time, many changes since DeskLib betas have
  124. not been documented particularly well.
  125.  
  126.  
  127.  
  128.  
  129. Other things
  130. ————————————
  131.  
  132. All code that used to call DeskLib's 'SWI' function now uses Acorn's
  133. '_swi'. One reason is that SWI would have to be modified (albeit fairly
  134. trivially) to work on the StrongARM. More importantly for me, SWI isn't
  135. ROM-able. Also, I think _swi is a lot easier to use.
  136.  
  137. I haven't built a SDLS version of Desk. The Jump library has untested
  138. support for the expensions to longjmp required by SDLS.
  139.  
  140. There are several versions of the library:
  141.  
  142.     C:Desk.o.Desk        Normally compiled.
  143.     C:Desk.o.Desk_D        Compiled with Desk_DEBUG predefined, so
  144.                 Desk_Debug_Printf statements are active.
  145.     C:Desk.o.Desk_M        Compiled with cc -zM, for use in module
  146.                 code.
  147.     C:Desk.o.Desk_M_D    Compiled with cc -zM and Desk_DEBUG
  148.                 predefined.
  149.     C:Desk.o.Desk_MC    Compiled for use with MemCheck, plus
  150.                 with cc -g, so can be used with DDT.
  151.  
  152.  
  153.  
  154.  
  155. ToDo
  156. ————
  157.  
  158. Auto-Freeing of resources after errors
  159.     
  160.     Resources have to be explicitly released whenever an error occurs, which
  161.     results in code like:
  162.     
  163.         {
  164.         void* volatile    ptr = NULL;
  165.         Desk_Error2_Try    {
  166.             ...
  167.             ptr = Desk_DeskMem_Malloc( ...);
  168.             ...
  169.             }
  170.         Desk_Error2_Catch    {
  171.             Desk_DeskMem_Free( ptr);
  172.             Desk_Error2_ReThrow();
  173.             }
  174.         Desk_Error2_EndCatch
  175.         
  176.         ...
  177.         }
  178.     
  179.     I have found this sort of code to occur very commonly. The problem is
  180.     that it is rather longwinded, and the call to setjmp made by
  181.     Desk_Error2_Try is probably rather slow (it has to save all registers
  182.     etc, and restricts the optimising that the compiler can carry out).
  183.     
  184.     Note that not using Desk_Error2 would still require 'ptr' to be freed in
  185.     case of error. One common way of doing this is to use the dreaded goto:
  186.     
  187.         {
  188.         void*    ptr = NULL;
  189.         os_error*    e;
  190.         ptr = malloc( ...);
  191.         if ( !ptr)    { e=...; goto error; }
  192.         if ( e=Foo( ...), e)    goto error;
  193.         if ( e=Bar( ...), e)    goto error;
  194.         ...
  195.         return NULL;
  196.         
  197.         error:
  198.         free( ptr);
  199.         return e;
  200.         }
  201.     
  202.     so the Desk_Error2 system isn't making code more difficult to write
  203.     really.
  204.     
  205.     Anyway, a way to avoid the try..catch blocks would be to make
  206.     Desk_DeskMem_Malloc put every malloc block in a singly-linked list, and
  207.     make Desk_Error2_Try store the last malloc block. Then when an error
  208.     occurrs, Desk_JumpAuto_Throw would automatically free all blocks up to
  209.     (and not including) the block registered by the last Desk_Error2_Try.
  210.     
  211.     This scheme could be extended to automatically call fclose() etc. It has
  212.     the drawback of adding a one word overhead to every malloc block.
  213.     
  214.     Note that in normal operation, no automatic freeing of blocks would
  215.     occur. If some allocated memory was required to be preserved even after
  216.     an error occurred, it would have to be allocated using something like
  217.     Desk_DeskMem_MallocPermanent() or something.
  218.     
  219.  
  220. Make Save library use Export.
  221.  
  222. Make SDLS version.
  223.  
  224. Use RCS.
  225.  
  226. Lots of other things...
  227.  
  228.  
  229.  
  230. Important note
  231. ——————————————
  232.  
  233. Even though I now work for Acorn, Desk has nothing to do with Acorn.
  234. It's status is the same as DeskLib - a freeware library supplied with
  235. all source and no support 8) .
  236.  
  237.  
  238. - Julian Smith
  239.  
  240. jsmith@acorn.co.uk
  241.  
  242.